Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: avoid colloquialism #12417

Closed
wants to merge 1 commit into from
Closed

doc: avoid colloquialism #12417

wants to merge 1 commit into from

Conversation

Trott
Copy link
Member

@Trott Trott commented Apr 15, 2017

I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat Optional:
to be consistent with how it appears elsewhere in the doc.

Checklist
Affected core subsystem(s)

doc

@Trott Trott added the doc Issues and PRs related to the documentations. label Apr 15, 2017
@mscdex mscdex added the meta Issues and PRs related to the general management of the project. label Apr 15, 2017
gibfahn
gibfahn suggested changes Apr 15, 2017
View reviewed changes
COLLABORATOR_GUIDE.md Outdated
@@ -345,7 +345,7 @@ Additionally:

### Technical HOWTO

_Optional:_ ensure that you are not in a borked `am`/`rebase` state
Optional: Clear any `am`/`rebase` that is already underway.
Copy link
Member

@gibfahn gibfahn Apr 15, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't really optional, it's necessary if you are in an am or rebase state. People who are less familiar with Git aren't going to know whether or not they need to do it.

Maybe say something like:

If git status shows Rebase in progress or You are in the middle of an am session., then you need to cancel the rebase or am with:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the optional label.

@gibfahn LGTY now?

@benjamingr
Copy link
Member

benjamingr commented Apr 15, 2017 •
edited
Loading

I'm +0. Googled borked to make sure and the first result explained it pretty well and borked is pretty common terminology.

Also, agree with @gibfahn regarding the optional part.

@refack
Copy link
Contributor

refack commented Apr 17, 2017 •
edited
Loading

I'm -1 -0.1±0.05 on the one hand, I like a little whimsy, and do we want this to turn into a git tutorial (since there are other, way better ones). But then again I'm old, I've actually contributed code to git, and I'm fluent in English.

But I'm suggesting a more extensive Edit (PR to come):
I would suggest we replace most of the git specific content with a pointer to a good tutorial as a step in one-week-before-the-onboarding-session leaving behind just the flow outline (never green "Merge", fetch PR localy, rebase+edit, test, push, pray, run another CI)

refack
refack reviewed Apr 17, 2017
View reviewed changes
COLLABORATOR_GUIDE.md
@@ -345,7 +345,7 @@ Additionally:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Up there (out of context) 309 & 311 are almost dups. also I'd pull "Please never use GitHub's green" down here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I digress, I'll do this myself.

@Trott
doc: avoid colloquialism
0e16016 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.
@Trott
Copy link
Member Author

Trott commented Apr 17, 2017

I'm +0. Googled borked to make sure and the first result explained it pretty well and borked is pretty common terminology.

@benjamingr FWIW (and it probably depends on what Google knows about you), when I Google "borked", the first thing I see is this definition:

obstruct (someone, especially a candidate for public office) through systematic defamation or vilification.

I think that's probably more confusing in this context than helpful.

jasnell pushed a commit that referenced this pull request Apr 18, 2017
@Trott @jasnell
doc: avoid colloquialism
296f331 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@jasnell
Copy link
Member

jasnell commented Apr 18, 2017

Landed in 296f331

@jasnell jasnell closed this Apr 18, 2017
@jasnell jasnell reopened this Apr 18, 2017
@jasnell jasnell closed this Apr 18, 2017
evanlucas pushed a commit that referenced this pull request Apr 25, 2017
@Trott @evanlucas
doc: avoid colloquialism
5796152 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@evanlucas evanlucas mentioned this pull request May 1, 2017
Merged
evanlucas pushed a commit that referenced this pull request May 1, 2017
@Trott @evanlucas
doc: avoid colloquialism
9241bbc 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
evanlucas pushed a commit that referenced this pull request May 2, 2017
@Trott @evanlucas
doc: avoid colloquialism
af0067c 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
gibfahn pushed a commit that referenced this pull request May 16, 2017
@Trott @gibfahn
doc: avoid colloquialism
6068bb7 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
MylesBorins pushed a commit that referenced this pull request May 18, 2017
@Trott @MylesBorins
doc: avoid colloquialism
3556c17 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: #12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@MylesBorins MylesBorins mentioned this pull request May 23, 2017
Merged
andrew749 pushed a commit to michielbaird/node that referenced this pull request Jul 19, 2017
@Trott @andrew749
doc: avoid colloquialism
d58d8f4 
I witnessed an English-as-a-second-language speaker puzzle over the word
"borked" in our documentation today. Reword to avoid colloquialisms.
It's more precise and clear this way anyway. Also reformat `Optional:`
to be consistent with how it appears elsewhere in the doc.

PR-URL: nodejs/node#12417
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@Trott Trott deleted the borked branch January 13, 2022 22:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@refack refack refack left review comments

@gibfahn gibfahn gibfahn approved these changes

@richardlau richardlau richardlau approved these changes

@lpinca lpinca lpinca approved these changes

@thefourtheye thefourtheye thefourtheye approved these changes

@jasnell jasnell jasnell approved these changes

Assignees
No one assigned
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
9 participants
@Trott @benjamingr @refack @jasnell @thefourtheye @lpinca @richardlau @gibfahn @mscdex